What to do for version 0.1

TG2D 0.1 will be simplest possible graphic future-compatible library.

INTERFACE
  0.1 will not have interface. Sources will be included directly into fasm project and
  user will call directly procedure bodies.


STRUCTURES:

  - due to fasm standard, sizeof.<struture> is structure's size. 
  - Keep in mind structures will grow in future
  - Order of member won't change unless there is some really important reason

  bitmap (bitmap header)
    unsigned dword Xsz,Ysz = sizes of bitmap in pixels. Must be in 0..2^31-1 because coordinates 
      are signed dwords so coordinte above 2^31-1 can't be specified. Values above 2^31-1 are
      invalid.
    dword bmp = pointer to array of Xsz*Ysz pixels contained in btimap.
    dword flags = flags of bitmap.
      80000000 = internal flag - notes that bitmap header was allocated by CreateBitmap (so it
                 is allocated in one chunk together with pixel array)
                 


PROCEDURE BODIES:

  Init
    desc:  initializes library, returns pointer to current display mode bitmap
    ret:   eax = current mode bitmap

  SetMode 
    desc:  sets display mode, returns pointer to video framebuffer (primary surface)
    args:  [ebx,ecx] = resolution, eax = bits per pixels, edi = bitmap header pointer
    ret:   eax = pointer to filled framebuffer bitmap, -1 on error
    - if edi is 0 new header will be allocated and returned in eax.
    - ebx and ecx must be in 0..2^31-1
    - 0.1 supports only 16 bpp
    - video framebuffer bitmap don't have to be freed (and can't be). It will be freed
      on next SetMode or ResetMode call

  ResetMode
    desc:  returns display mode to state it was in when Init was called

  CreateBitmap
    desc:  allocates new bitmap with undefined contents
    args:  unsigned [ebx, ecx] = bitmap size, edi = bmp header pointer, eax = bitmap flags, must be 0
    ret:   eax = bitmap header pointer, -1 on error
    - if edi is 0 new header will be allocated and returned in eax.

  FreeBitmap
    desc:  frees bitmap from memory
    args:  eax = bitmap
    ret:   eax = 1 is succeed, -1 on error
    - NOTE: if bitmap header was allocated by CreateBitmap it wil free it too. Otherwise
      only piece of memory pointed by eax->bmp is freed, and eax->bmp is set to 0.
    - video framebuffer bitmap (returned by SetMode) can't be freed with this procedure.

  Draw
    desc:  draws bitmap onto another bitmap
    args:  edi = dest bitmap pointer, esi = source bitmap pointer, 
           signed [ebx,ecx] = coords in dest bitmap where to draw
    ret:   eax = -1 on error, 1 if succeed
    - NOTE: if part of source bitmap is out of destination bitmap it will be clipped,
      if whole source bitmap is out of destination bitmap, nothing will be drawn
    
  GetVerticalRetrace
    desc:  gets status of vertical retrace (vertical blank)
    args:  none
    ret:   eax = 1 if vertical retrace is occuring, 0 otherwise
    - NOTE: doesnt return -1 in eax, error checking is not needed


ROUTINES:

  Draw_DestPos
    args:  edi = dest bitmap, esi = src bitmap, [ebx,ecx] = coords in dest bitmap where to draw



OS ACCESS:

  OS_SetMode
    desc:  OS dependant part of SetMode
    args:  [ebx,ecx] = resolution, eax = bits per pixel
    ret:   eax = video framebuffer pointer

  OS_GetVerticalRetrace
    desc:  OS dependant part of GetVerticalRetrace
    args:  none
    ret:   eax = 1 if vertical retrace is occuring, 0 otherwise
    - NOTE: whole GetVerticalRetrace is OS dependant, but it must be defined as procedure body
      too, we cant let user call procedure defined as OS access. Solution is to redirect procedure
      body GetVerticalRetrace to OS access procedure OS_GetVerticalRetrace:
        label GetVerticalRetrace at OS_GetVerticalRetrace
    
  allocmem
    desc:  allocates memory with undefined contents
    args:  unsigned eax = size of memory to allocate in bytes
    ret:   eax = pointer to allocated memory

  freemem
    desc:  releases allocated memory
    args:  eax = pointer to allocated memory


(THEORETICAL) EXAMPLE PROGRAM USING 0.1:
  Init()
  modebmp = TG2D.SetMode(ebx=640, ecx=480, eax=16)
  backbmp = TG2D.CreateBitmap(ebx=640, ecx=480, eax=0)
  pic = TG2D.CreateBitmap(ebx=20, ecx=30, edi=0, eax=0)
  ramp-fill bitmap
  loop
    TG2D.Draw(esi=pic, edi=backbmp, ebx=posX, ecx=posY)
    randomly change posX and posY
    loop while TG2D.VerticalRectrace() == 1
    loop while TG2D.VerticalRectrace() == 0
    TG2D.Draw(esi=backbmp, edi=modebmp, ebx=0, ecx=0)
  until ESC pressed
  TG2D.FreeBitmap(eax = pic)
  TG2D.FreeBitmap(eax = backbmp)
